To integrate hand-built themes with iMIS sites
In conformance with standard ASP.NET conventions, each theme must be placed in a uniquely named folder inside the ~\App_Themes folder in the physical path for each IIS application and IIS web site used for hosting iMIS sites. This ensures that the theme name will be selectable when defining an iMIS site. The name you use for the folder is the name that users will see when choosing a theme for the iMIS site.
To ensure that all iMIS functionality is styled correctly, the best approach for developing new themes is to start with a copy of an existing theme, instead of trying to develop a new theme entirely from scratch.
To integrate hand-built master pages with iMIS sites
Each master page must be placed in the ~\Templates\MasterPages folder in the physical path for each IIS application and IIS web site used for hosting iMIS sites.
When developing a new master page, you must ensure that certain required ASP.NET classes are inherited and that certain required elements are used. There are also many optional elements that you might want to use. These classes and elements are described in the following sections.
Caution! Omitting the non-required elements will not result in an error in iMIS 15.1, but this might change in future releases. To be safe, you should include these elements in your master page even if they are undesired at present, and use a visible="false" attribute in each one that you do not want to display.
Note: To see examples of how these elements should be used in a hand-built master page, examine one of the Sample Site’s master page’s, such as Forest.master, or Planets.master.
Required classes
■ All master pages must inherit the Asi.Web.UI.MasterPageBase class, located in the Asi.Web assembly. This class provides base functionality for integration with iMIS. For example:
<%@ Master Language="C#" Inherits="Asi.Web.UI.MasterPageBase" %>
■ If you intend to use content areas and a different page layout for your Home page versus every other page on the site, then you should not directly inherit the Asi.Web.UI.MasterPageBase class, but instead inherit the Asi.Web.UI.TemplateGalleryMasterPageBase class (which in turn inherits the Asi.Web.UI.MasterPageBase class). For example:
<%@ Master Language="C#" Inherits="Asi.Web.UI.TemplateGalleryMasterPageBase" %>
Required elements in all master pages
The following elements are required on every master page regardless of which base class the master page inherits:
■ The head element must contain a child asp:ContentPlaceHolder element with an id attribute of TemplateHead. For example:
<asp:ContentPlaceHolder runat="server" id="TemplateHead">
■ The body element must contain a single child form element with an id attribute of TemplateForm. The runat attribute for this element must be server. This form element must be the only child of the body element and all DIV-based layout must be contained within this form element. For example:
<form runat="server" id="TemplateForm" method="post"></form>
■ The asp:panel element with id="ContentPanel", which comprises the Main Content Area of an interior page, must contain the two following elements:
□ An asp:ContentPlaceHolder element with an id attribute of TemplateUserMessages. This displays non-fatal error and warning messages on pages. For example:
<asp:ContentPlaceHolder runat="server" id="TemplateUserMessages">
□ An asp:ContentPlaceHolder element with an id attribute of TemplateBody. This is where the rendered output of a content record is typically displayed. For example:
<asp:ContentPlaceHolder runat="server" id="TemplateBody">
■ The asp:Panel element with id="ButtonPanel", which conditionally displays the Save, Cancel, etc. buttons at the bottom of the Main Content Area of an interior page, must contain an asp:ContentPlaceHolder element with an id attribute of TemplateButtonBar. For example:
<asp:ContentPlaceHolder runat="server" id="TemplateButtonBar">
■ The asp:Panel element with id="SubNavPanel", which comprises the default Secondary navigation area of page, must contain an asp:ContentPlaceHolder element with an id attribute of SideBarPlaceHolder. This is used to display additional context-sensitive navigation information, such as clustered page navigation. For example:
<asp:ContentPlaceHolder runat="server" id="SideBarPlaceHolder">
Additional required elements in master pages that inherit the TemplateGalleryMasterPageBase class
If the master page is inheriting the Asi.Web.UI.TemplateGalleryMasterPageBase class, then to provide support for a Home page that uses a different page layout from all the interior pages of the site you must also include the following elements:
■ The DIV that is the immediate child of the form element must contain an asp:Panel element with id="HomePageContent". This asp:Panel element must in turn contain an asp:ContentPlaceHolder element with an id attribute of HomePageBody. This set of elements provides support for a Home Page that uses a different layout from the interior pages. For example:
<asp:Panel ID="HomePageContent" runat="server">
<asp:ContentPlaceHolder ID="HomePageBody" runat="server" />
</asp:Panel>
■ The script element should include the following code:
<script language="C#" runat="server">
override protected void EnsureContentAreas()
{
HomepageContentAreas = new System.Collections.Generic.List<ContentTemplateArea>(
new ContentTemplateArea[]
{
HomepageContentArea1,
HomepageContentArea2,
HomepageContentArea3,
// List all homepage content areas here
});
InteriorContentAreas = new System.Collections.Generic.List<ContentTemplateArea>(
new ContentTemplateArea[]
{
ContentArea1,
ContentArea2,
ContentArea3,
// List all non-homepage content areas here
});
}
override protected SiteMapNode GetStartingNode()
{
return Secondary.GetStartingNode();
}
override protected SiteMapNode GetCurrentNode()
{
return Secondary.GetCurrentNode();
}
// Remove this if you omit the login/logout control.
protected void LoginStatus1_OnLoggedOut(object sender, EventArgs e)
{
Asi.Web.Security.RevokeAppContext(HttpContext.Current);
if (Page is Asi.Web.UI.DisplayPageBase && ((Asi.Web.UI.DisplayPageBase)Page).iMISWebsite != null)
Response.Redirect(((Asi.Web.UI.DisplayPageBase)Page).iMISWebsite.WebsiteLink, true);
else
Response.Redirect(System.Web.Security.FormsAuthentication.DefaultUrl, true);
}
</script>
To add content areas
If your master page is replacing a default Sample Site master page, you must provide controls to display the content designated for content areas in the template's Home and interior pages. You do this by adding the following element to the master page wherever you want the content area to appear:
<asiweb:ContentTemplateArea id="ContentArea1" TemplateAreaName="ContentArea1" runat="server" />
The id attribute is not used by iMIS, so it can be any value. The TemplateAreaName attribute indicates which content record to display in this content area. The value you specify must match the name of a content record located in the site's special ContentAreas content folder (@/[WebsiteName]/ContentAreas by default, in the Content Designer content folder hierarchy).
To enable home page content layouts in master pages
If you want to use content layouts in your template master page, you must enable a property. You do this by adding the following markup to the content areas for the master page.
1. Find this control markup in the page:
<asiweb:ContentTemplateArea
2. Add the following property setter to that control: "HonorContentRecordLayout="true"".
3. Repeat for each content area that you want to honor the layout. The resulting line should appear like so:
<asiweb:ContentTemplateArea id="HomepageContentArea2" templateareaname="HomepageContentArea2" HonorContentRecordLayout="true" runat="server" />
To add the top bar controls
The top bar controls comprise the Sign In / Sign Out link and the icon that toggles Surf-to-Edit mode on and off. You can place these controls in anywhere on the page.
■ The control for the Sign In / Sign Out link must be defined with the following asp:LoginStatus element:
<asp:LoginStatus ID="LoginStatus1" runat="server" LoginText="Log On" LogoutText="Log Off"
AccessKey="l" OnLoggedOut="LoginStatus1_OnLoggedOut" CssClass="LoginStyles" />
■ The control for the icon that toggles Surf-to-Edit mode must be defined with the following asp:ContentPlaceHolder element:
<asp:ContentPlaceHolder ID="AuxiliaryNavigationSupplementalContent" runat="server">
</asp:ContentPlaceHolder>
To add a browser session keep-alive control
The browser session keep-alive control forces a user's session and logon credentials to remain active as long as they keep the browser open, which prevents them from being required to re-authenticate to IIS if they do not use the site for an extended period of time. This control is defined with a pair of elements:
<asp:Label ID="KeepAliveTarget" runat="server" Text=" " />
<asiweb:KeepAliveExtender ID="KeepAliveControl" runat="server" TargetControlID="KeepAliveTarget" />
These elements may be located in the same DIV that contains the Auxiliary navigation area, but there is nothing that requires them to be located there.
To add a basic search control
Define a DIV element to be used as a container for the search form control, and this DIV element must contain the following asiweb:SimpleSearchField element:
<asiweb:SimpleSearchField ID="SearchField" runat="server" AdvancedLinkVisible="false"
ButtonCssClass="SearchButton" InputCssClass="Watermarked" />
More about the AdvancedLinkVisible attribute:
■ (recommended) Leave this attribute set to false. The preferred method for creating advanced search forms is to create a single AdvancedSearch iPart in a content record that is the target of a navigation item with Navigation Link Text such as Advanced Search.
■ If you set this attribute to true and add a SearchTargetUrl attribute (for example, SearchTargetUrl="~/MyAdvancedSearch.aspx"), the basic search control in your site will include an Advanced Search link, which will display the target .aspx page. This technique lets you use a hand-built advanced search page for the site.
Tip: You can also modify the basic search control by adding additional attributes not shown in the preceding code sample. See Extending the default search behavior.
To add the page task controls
The page task controls comprise a set of three icons that enable the user to display a printable version of the page, display a text-only version of the page, or to email the page's URL to a friend. These are typically located at the bottom left of each page in the Sample Sites.
Define a DIV element to be used as a container for the page task controls. This DIV element must contain the following asp:Panel element:
<asp:Panel ID="PageTasksPanel" runat="server" CssClass="PageTasksPanel NotPrinted">
<span style="margin:auto;">
<asp:ContentPlaceHolder ID="TemplatePageTasks" runat="server">
</asp:ContentPlaceHolder>
</span>
</asp:Panel>
Troubleshooting
■ You must have developed your hand-built master pages and themes in accordance with ASP.NET best practices and requirements.
■ You must have administrative access to the entire file system on your iMIS application server and on all the external web servers that you use for hosting iMIS sites.
■ The root of all file paths used in the following sections is denoted by ~, and corresponds to the root of the physical path for each IIS application or IIS web site used for hosting iMIS sites. For example, in a Complete installation of iMIS where the iMIS application is used for hosting iMIS sites, the default physical path is C:\Program Files\ASI\iMIS\Net, so the Net folder is the root (~).